home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Experimental BBS Explossion 3
/
Experimental BBS Explossion III.iso
/
pascal
/
pcl4p40.zip
/
PCL4P.REF
< prev
next >
Wrap
Text File
|
1993-10-17
|
62KB
|
2,401 lines
Personal Communications Library
For the Turbo Pascal
( PCL4P )
REFERENCE MANUAL
Version 4.0
Oct 18, 1993
This software is provided as-is.
There are no warranties, expressed or implied.
Copyright (C) 1993
All rights reserved
MarshallSoft Computing, Inc.
Post Office Box 4543
Huntsville AL 35815
Voice 205-881-4630
FAX 205-881-4630
BBS 205-880-9748
PCL4P Reference Manual Page 1
C O N T E N T S
Chapter Page
Table of Contents......................................2
Introduction...........................................3
SioBaud.............................................4
SioBrkKey...........................................5
SioBrkSig...........................................6
SioCTS..............................................7
SioDCD..............................................8
SioDelay............................................9
SioDone............................................10
SioDSR.............................................11
SioDTR.............................................12
SioError...........................................13
SioFIFO............................................14
SioFlow............................................15
SioGetc............................................16
SioInfo............................................17
SioIRQ.............................................18
SioLine............................................19
SioLoopBack........................................20
SioModem...........................................21
SioParms...........................................22
SioPorts...........................................23
SioPutc............................................24
SioRead............................................25
SioReset...........................................26
SioRI..............................................27
SioRTS.............................................28
SioRxBuf...........................................29
SioRxFlush.........................................30
SioRxQue...........................................31
SioTimer...........................................32
SioTxBuf...........................................33
SioTxFlush.........................................34
SioTxQue...........................................35
SioUART............................................36
SioUnGetc..........................................37
Function Summary......................................38
Error Code Summary....................................39
PCL4P Reference Manual Page 2
Introduction
This manual list all the PCL4P functions in alphabetical order.
Every library function will return a value as follows:
1. Negative values for error conditions. See last page of this
manual for a list of error values and their meanings.
2. Non-negative values when returning data ( eg: SioLine ).
3. Zero otherwise.
When debugging an application, be sure to test all return values.
Use SioError to print the associated text for errors.
Example Code Segment
**********************************************************
* RetCode := SioFunction(); (* any PCL4P function *) *
* if RetCode < 0 then begin *
* RetCode := SioError(RetCode); *
* (* ...do some stuff... *) *
* end; *
**********************************************************
For more examples, examine each of the example programs provided.
Also look at the examples associated with each library function
described in the following section.
PCL4P Reference Manual Page 3
SioBaud
Function Sets the baud rate of the selected port.
Syntax function SioBaud(Port,BaudCode:Integer) : Integer;
Remarks The SioBaud function sets the baud rate without
resetting the port. It is used to change the baud rate
after calling SioReset.
Baud Code Baud Rate PCL4P.H Name
0 300 Baud300
1 600 Baud600
2 1200 Baud1200
3 2400 Baud2400
4 4800 Baud4800
5 9600 Baud9600
6 19200 Baud19200
7 38400 Baud38400
8 57600 Baud57600
9 115200 Baud115200
Returns -4 : Port out of range. Expecting 0 to 3.
-11 : Bad baud rate code. See above code values.
Example
/* do auto baud detect */
for Code = 0 to 9 do begin
RetCode := SioBaud(Port,Code);
RetCode := SioPutc(Port,'A');
if SioGetc(Port,18) = Ord('A') then
begin
writeln('Baud rate detected');
(*...do something here...*)
end
end;
See Also SioReset
PCL4P Reference Manual Page 4
SioBrkKey
Function Return non-zero if the Control-BREAK key was pressed.
Syntax function SioBrkKey : Integer;
Remarks The SioBrkKey function returns a TRUE value ( non zero
) if the Control-BREAK key was pressed, else it
returns a zero. Use SioBrkKey as a safety exit from a
polling loop. Don't mix this function up with
SioBrkSig.
Returns -1 : Control-BREAK was pressed.
0 : Control-BREAK was NOT pressed.
Example
if SioBrkKey then
begin
writeln('User typed Contrl-BREAK');
RetCode := SioDone(Port);
halt;
end;
See Also SioBrkSig
PCL4P Reference Manual Page 5
SioBrkSig
Function Asserts, cancels, or detects BREAK signal.
Syntax function SioBrkSig(Port:Integer;Cmd:Char) : Boolean;
Remarks The SioBrkSig function controls the BREAK bit
in the line status register. The legal commands are:
ASSERT ('A') to assert BREAK
CANCEL ('C') to cancel BREAK
DETECT ('D') to detect BREAK
ASSERT, CANCEL, and DETECT are defined in PCL4P.H.
See TERM.C for an example of the use of SioBrkSig.
Returns -2 : Port not enabled. Call SioReset first.
-4 : Port out of range. Expecting 0 to 3.
-6 : Illegal command. Expected 'A', 'C', or 'D'.
>0 : BREAK signal detected ( DETECT command only )
Example
(* Assert BREAK for 1 second *)
RetCode := SioBrkSig(Port,ASSERT);
RetCode := SioDelay(18);
RetCode := SioBrkSig(Port,CANCEL);
(* Detect BREAK *)
if SioBrkSig(Port,DETECT) then
begin
writeln('BREAK signal detected');
(* ...do some more stuff... *)
end
See Also SioBrkKey
PCL4P Reference Manual Page 6
SioCTS
Function Reads the Clear to Send ( CTS ) modem status bit.
Syntax function SioCTS(Port:Integer) : Integer;
Remarks The SioCTS function is used to read the Clear to Send (
CTS ) modem status bit.
Returns -2 : Port not enabled. Call SioReset first.
-4 : Port out of range. Expecting 0 to 3.
0 : CTS is clear.
>0 : CTS is set.
Example
(* read CTS line *)
RetCode := SioCTS(Port);
if RetCode > 0 then write('CTS is set');
else write('CTS is clear');
See Also SioDSR, SioRI, SioDCD, and SioModem.
PCL4P Reference Manual Page 7
SioDCD
Function Reads the Data Carrier Detect ( DCD ) modem status
bit.
Syntax function SioDCD(Port:Integer) : Integer;
Remarks The SioDCD function is used to read the Data Carrier
Detect ( DCD ) modem status bit. Also see SioModem.
Returns -2 : Port not enabled. Call SioReset first.
-4 : Port out of range. Expecting 0 to 3.
0 : DCD is clear.
>0 : DCD is set.
Example
(* read DCD line *)
RetCode := SioDCD(Port);
if RetCode > 0 then write('DCD is set');
else write('DCD is clear');
See Also SioDSR, SioCTS, SioRI, and SioModem.
PCL4P Reference Manual Page 8
SioDelay
Function Delays one or more tics.
Syntax function SioDelay(Tics:Integer) : Integer;
Remarks The SioDelay function is used to delay one or more
timer tics, where each timer tic is approximately 55
milliseconds ( 18 to the second ).
Returns zero
Example (* delay 5 seconds *)
RetCode := SioDelay(5*18);
See Also SioTimer
PCL4P Reference Manual Page 9
SioDone
Function Terminates further serial processing.
Syntax function SioDone(Port:Integer) : Integer
Remarks The SioDone function terminates further serial
processing. SioDone MUST be called before exiting your
application so that interrupts can be restored to
their original state. Failure to do this can crash the
operating system. If you forget to call SioDone
before exiting, be sure to re-boot your computer. You
can call SioDone even if SioReset has not been called,
so it is good practice to always call SioDone before
exiting your application.
Returns -2 : Port not enabled. Call SioReset first.
-4 : Port out of range. Expecting 0 to 3.
Example (* terminate processing for COM3 *)
RetCode := SioDone(COM3);
See Also SioReset.
PCL4P Reference Manual Page 10
SioDSR
Function Reads the Data Set Ready ( DSR ) modem status bit.
Syntax function SioDSR(Port:Integer) : Integer;
Remarks The SioDSR function is used to read the Data Set
Ready ( DSR ) modem status bit.
Returns -2 : Port not enabled. Call SioReset first.
-4 : Port out of range. Expecting 0 to 3.
0 : DSR is clear.
>0 : DSR is set
Example
(* read DSR line *)
RetCode := SioDSR(Port);
if RetCode > 0 then write('DSR is set');
else write('DSR is clear');
See Also SioCTS, SioRI, SioDCD, and SioModem
PCL4P Reference Manual Page 11
SioDTR
Function Set, clear, or read the Data Terminal Ready ( DTR )
bit.
Syntax function SioDTR(Port,Cmd:Integer) : Integer;
Remarks The SioDTR function controls the Data Terminal Ready (
DTR ) bit in the modem control register. Commands (
defined in PCL4P.H ) are:
SetPort ('S') to set DTR ( ON )
ClrPort ('C') to clear DTR ( OFF )
ReadPort ('R') to read DTR
Returns -2 : Port not enabled. Call SioReset first.
-4 : Port out of range. Expecting 0 to 3.
-5 : Not one of 'S', 'C', or 'R'.
0 : DTR is OFF (READ Command).
>0 : DTR is ON (READ Command).
Example
(* turn DTR on for modem connected to COM4 *)
RetCode := SioDTR(COM4,SetPort);
See Also SioRTS.
PCL4P Reference Manual Page 12
SioError
Function Displays error in text.
Syntax function SioError(Code:Integer) : Integer;
Remarks The SioError function displays the error in text
corresponding to the error code. During development
of a communications application, it is a good idea to
always test return codes, and print out their
descriptions with SioError.
Returns zero
Example
(* display error text if error on Reset *)
RetCode := SioReset(Port,Baud4800);
if RetCode < 0 then RetCode := SioError(RetCode);
PCL4P Reference Manual Page 13
SioFIFO
Function Sets the FIFO trigger level ( INS16550 only ).
Syntax Function SioFIFO(Port,LevelCode:Integer) : Integer
Remarks The SioFIFO function is used to set the trigger level
at which interrupts are generated. For example, if the
FIFO level is set to 8, then the INS16550 UART will
not generate an interrupt until 8 bytes have been
received. This reduces the number of interrupts
generated and allows faster processing with slower
machines or when running simultaneous ports.
In order to test if your port is a INS16550, call
SioFIFO with a LevelCode of other than FIFO_OFF.
SioFIFO can be called for the INS8250 without ill
effect.
Code PCL4C.H Name Trigger Level
-1 FIFO_OFF Disable FIFO
0 LEVEL_1 1 byte
1 LEVEL_4 4 bytes
2 LEVEL_8 8 bytes
3 LEVEL_14 14 bytes
Returns -2 : Port not enabled. Call SioReset first.
-4 : Port out of range. Expecting 0 to 3.
>0 : FIFO level set.
0 : FIFO level not set ( not INS16550 ).
Example (* Set FIFO level to 8 *)
if SioFIFO(Port,LEVEL_8) then writeln('FIFO reset')
else writeln('UART in not INS16550');
PCL4P Reference Manual Page 14
SioFlow
Function Sets hardware (RTS/CTS) flow contol.
Syntax Function SioFIFO(Port,Tics:Integer) : Integer
Remarks The SioFlow function is used to enable or disable
hardware fow control. Hardware flow control uses RTS
and CTS to control data flow between the modem and the
computer. Refer to the User's Manual for a discussion
of flow control. To enable hardware flow control, call
SioFlow with Tics > 0.
"Tics" is the number of timer tics (18 per second)
before a call to SioPutc will time out because because
the modem dropped CTS.
In order for hardware flow control to work correctly,
your modem must also be configured to work with
hardware flow control, and your computer to modem
cable must have RTS and CTS wired staright through. if
you enable hardware flow control, do not modify the
RTS line (by calling SioRTS) unless you know exactly
what you are doing.
Flow control is disabled after resetting a port. To
explicitly disable hardware flow contol, call SioFlow
with Tics = -1.
Returns -2 : Port not enabled. Call SioReset first.
-4 : Port out of range. Expecting 0 to 3.
=0 : Flow control disabled.
>0 : Flow control enabled.
Example (* Enable flow control on COM1 *)
Code := SioFlow(COM1,18);
if Code > 0 then WriteLn('Flow control enabled')
else Code := SioError(Code);
(* Disable flow control on COM2 *)
Code := SioFlow(COM2,-1);
if Code = 0 then WriteLn('Flow control disabled')
else Code := SioError(Code);
Also See SioPutc
PCL4P Reference Manual Page 15
SioGetc
Function Reads the next character from the serial line.
Syntax function SioGetc(Port,Tics:Integer) : Integer;
Remarks The SioGetc function reads the selected serial port.
The function will wait for the number of system tics
given by the 'Tics' argument before returning 'timed
out'. There are 18 tics to the second.
To specify no waiting, call SioGetc with Tics = 0.
Returns -2 : Port not enabled. Call SioReset first.
-4 : Port out of range. Expecting 0 to 3.
-1 : If timed out.
>0 : Character read.
Example
(* get next character from COM1 *)
RetCode := SioGetc(COM1,1);
if RetCode <> -1
then writeln('Character is ', chr(RetCode) );
else writeln('Timed out');
See Also SioUnGetc and SioPutc.
PCL4P Reference Manual Page 16
SioInfo
Function Returns PCL4P library version number.
Syntax function SioInfo(Cmd : Char) : Integer;
Remarks The SioInfo function returns an integer code
corresponding to the library version number.
Returns
Version ('V')
hex byte XY where version is denoted as X.Y
TX Interrupts ('I')
0 if transmitter interrupts are disabled in the
library, otherwise returns other than 0.
Example (* return version number *)
Version := SioInfo('V');
WriteLn('Version ',Version div 16,Version mod 16);
Write('TX Interrupts are ');
if SioInfo('I') then WriteLn('enabled');
else WriteLn('disabled');
PCL4P Reference Manual Page 17
SioIRQ
Function Assigns an IRQ line to a port.
Syntax function SioIRQ(Port,IRQcode):Integer;
Remarks The SioIRQ function assigns an IRQ line to a port.
SioIRQ (like SioUART) must be called before calling
SioReset in order to have any effect. Unless you have
a non-standard serial port configuration, you will
never need to call SioIRQ.
In particular, remember that your port hardware must
generate the interrupt that you have specified. Also
be carefull about conflicting interrupt assignments.
Be sure to call SioPorts first to setup DigiBoard
ports if you have them. Refer to the PCL4P Users
Manual for additional information.
Returns -4 : Port out of range. Expecting 0 to 3.
-15 : Port already enabled. SioReset already called.
-17 : No such IRQ. ( should be 0 to 7).
-18 : No such ISR. (should be 0 to 4).
0 : Otherwise
Example (* use IRQ5 for COM3 -- non-DigiBoard port*)
rc := SioUART(COM3,0x3220);
rc := SioIRQ(COM3,IRQ5);
(* we can now run 3 ports concurrently *)
...
See Also SioUART and SioPorts.
PCL4P Reference Manual Page 18
SioLine
Function Reads the line status register.
Syntax function SioLine(Port:Integer) : Integer;
Remarks The SioLine function reads the line status register.
The individual bit masks are as follows:
0x40 = Transmitter empty.
0x20 = Transmitter buffer empty.
0x10 = Break detected.
0x08 = Framming error.
0x04 = Parity error.
0x02 = Overrun error.
0x01 = Data ready.
The above are documented in the file PCL4P.H.
Returns -2 : Port not enabled. Call SioReset first.
-4 : Port out of range. Expecting 0 to 3.
>0 : Line status ( rightmost byte of word ).
Example
(* decode line register *)
RetCode := SioLine(Port);
if(RetCode and
(FramingError or ParityError or OverrunError)) <> 0
then begin
if (RetCode and FramingError) <> 0
then writeln('Framing Error');
if (RetCode and ParityError) <> 0
then writeln('Parity Error');
if (RetCode and OverrunError) <> 0
then writeln('Overrun Error')
end
else writeln('No error');
See Also SioModem & SioRead.
PCL4P Reference Manual Page 19
SioLoopBack
Function Does a UART loopback test.
Syntax function SioLoopBack(Port:Integer) : Integer;
Remarks SioLoopBack makes use of the built in loopback test
capability of the INS8250 UART. Normally SioLoopBack
will never need to be called except if you suspect
that your UART is bad. See the LOOPBACK.C program.
Returns 0 : Loopback test is successfull.
-2 : Port not enabled. Call SioReset first.
-4 : Port out of range. Expecting 0 to 3.
-12 : Loopback test fails.
Example
(* perform loopback test *)
RetCode := SioLoopBack(Port);
if RetCode = 0
then write('Loopback test has succeeded');
else write('Loopback test has failed');
PCL4P Reference Manual Page 20
SioModem
Function Reads the modem status register.
Syntax function SioModem(Port:Integer; Mask:Char) ; Integer;
Remarks The SioModem function reads the modem register. The
bit definitions for the function mask are as follows:
Bit Name Function
7 DCD Data Carrier Detect
6 RI Ring Indicator
5 DSR Data Set Ready
4 CTS Clear To Send
3 DeltaDCD Delta DCD ( DCD has changed )
2 DeltaRI Delta RI ( RI has changed )
1 DeltaDSR Delta DSR ( DSR has changed )
0 DeltaCTS Delta CTS ( CTS has changed )
Bits 4 through 7 represent the absolute state of their
respective RS-232 inputs. Bits 0 through 3 repesent a
change in the state of their respective RS-232 inputs
since last read.
The above definitions are also in the PCL4P.H file for
use by your application program.
Returns -2 : Port not enabled. Call SioReset first.
-4 : Port out of range. Expecting 0 to 3.
>0 : Modem status ( rightmost byte of word ).
Example
(* any change in DCD ? *)
Status := SioModem(Port,DeltaDCD);
if Status < 0 then
begin
RetCode := SioError(Status);
Halt;
end;
else writeln('DCD status = ', SioModem(Port,DCD) );
See Also SioCTS, SioDCD, SioDSR and SioRI.
PCL4P Reference Manual Page 21
SioParms
Function Sets parity, stop bits, and word length.
Syntax function SioParms(Port,ParityCode,StopBitsCode,
WordLengthCode:Integer) : Integer;
Remarks The SioParms function sets the parity, stop bits, and
word length. If the default parity ( none ), stop
bits ( 1 ), or word length ( 8 ) is not acceptable,
then they can be changed by calling SioParms. SioParms
can be called either before or after calling SioReset.
See file PCL4P.H.
Value Description PCL4P.H Name
ParityCode: *0 no parity NoParity
1 odd parity OddParity
3 even parity EvenParity
StopBitsCode: *0 1 stop bit OneStopBit
1 2 stop bits TwoStopBits
WordLengthCode: 0 5 data bits WordLength5
1 6 data bits WordLength6
2 7 data bits WordLength7
*3 8 data bits WordLength8
* = Default
Returns -4 : Port out of range. Expecting 0 to 3.
-7 : Bad parity code selected. Expecting 0 to 2.
-8 : Bad stop bits code. Expecting 0 or 1.
-9 : Bad word length code. Expecting 0 to 3.
Example
(* set serial parameters *)
RetCode := SioParms(COM1,NoParity,OneStopBit,WordLength8);
See Also SioReset.
PCL4P Reference Manual Page 22
SioPorts
Function To set the number of ports, the 1st DigiBoard port
and the DigiBoard status register address.
Syntax function SioPorts(NumberPorts,FirstPort,StatusReg :
Integer) : Integer;
Remarks The SioPorts function must be called before ANY other
serial functions. The purpose of the SioPorts function
is to set the total number of ports, the first
DigiBoard port and the DigiBoard status register
address.
Once SioPorts is called, all COM ports starting with
"FirstPort" will be treated as DigiBoard ports. The
default setup is 4 standard PC ports and no DigiBoard
ports [ SioPorts(4,4,0); ].
The standard DigiBoard status register is 0x140. If
you change this address on your DigiBoard, be sure
to specify the correct value for "StatusReg".
Returns -4 : No such port. Expect 0 to 11.
0 : No error (sets MaxPort to NumberPorts-1).
Example /* Want 2 PC ports & 8 DigiBoard ports (on PC/8) */
Code := SioPorts(10,COM3,$140);
/* Want 1 PC port & 4 DigiBoard ports (on PC/4) */
Code := SioPorts(5,COM2,$140);
See Also SioUART, SioIRQ.
PCL4P Reference Manual Page 23
SioPutc
Function Transmit a character over a serial line.
Syntax function SioPutc(Port:Integer; Ch:Char) : Integer;
Remarks The SioPutc function transmits one character over the
selected serial line.
If flow control has been enabled, then SioPutc may
return a -1 (time out) if the number of tics specified
in the SioFlow function was exceeded waiting for the
modem to raise CTS. Refer to the User's Manual for a
discussion of flow control.
Returns -2 : Port not enabled. Call SioReset first.
-4 : Port out of range. Expecting 0 to 3.
-1 : Timed out waiting for CTS (flow control enabled)
Example
(* compute & output the CRC *)
crc := 0;
for i = 0 to 127 do
begin
crc := crcupdate( buffer[i], crc);
RetCode := SioPutc(Port, buffer[i]);
end;
RetCode := SioPutc(crc);
See Also SioGetc and SioFlow.
PCL4P Reference Manual Page 24
SioRead
Function Reads any UART register.
Syntax function SioRead(Port,Reg:Integer) : Integer;
Remarks The SioReset function directly reads the contents of
any of the 7 UART registers. This function is useful
when debugging application programs, and as a method
for verifying UART contents.
The line status register (register 5) can also be read
with SioLine while the modem status register (register
6) can also be read with SioModem.
Refer to the PCL4P User's Manual for a discussion of
the UART registers.
Returns -3 : No buffer available. Call SioRxBuf first.
-4 : Port out of range. Expecting 0 to 3.
Example Reg : Integer; (* UART register *)
Contents : Integer; (* Contents of UART *)
(* print contents of 7 UART registers *)
for Reg=0 to 7 do
begin
Contents = SioRead(Port,Reg);
WriteLn('COM',1+Port,
' UART Register ',Reg,
' = ',Contents);
end;
PCL4P Reference Manual Page 25
SioReset
Function Initialize a serial port for processing.
Syntax function SioReset(Port,BaudCode:Integer) : Integer;
Remarks The SioReset function initializes the selected serial
port. SioReset should be called after calling SioParm
and SioRxBuf but before making any other calls to
PCL4P. SioReset uses the parity, stop bits, and word
length value previously set if SioParm was called,
otherwise the default values ( see SioParm ) are used.
Recall that COM1 and COM3 share the same interrupt
vector and therefore cannot operate simultaneously.
Similiarly, COM2 and COM4 cannot operate
simultaneously. Any other combination of two ports can
be used.
By specifing NORESET ( -1 ) for the baud rate code,
the port will NOT be reset. This is used to "take
over" a port from a host communications program that
allows a "DOS gateway". External protocols can be
implemented this way. See SioBaud for a list of the
baud rate codes, or see "PCL4P.H".
Returns -3 : No buffer available. Call SioRxBuf first.
-4 : Port out of range. Expecting 0 to 3.
-11 : Bad baud rate code selected. Expecting 0 to 9.
-13 : UART undefined. SioUART(Port,0) was called
previously.
-14 : Bad or missing UART. You may not have hardware
present.
-15 : Port already enabled. SioReset has already been
called.
-16 : Cannot enable both COM1 & COM3 or COM2 & COM4.
Example
RetCode := SioRxBuf(COM1,Ofs(Buffer),Seg(Buffer),Size128);
RetCode := SioReset(Com1,Baud38400);
if RetCode = 0 then writeln('RESET ok');
else begin
RetCode := SioError(rc);
if (RetCode and OverrunError) <> 0
then writeln('Overrun Error');
if (RetCode and ParityError) <> 0
then writeln('Parity Error');
if (RetCode and FramingError) <> 0
then writeln('Framing Error');
if (RetCode and BreakDetected) <> 0
then writeln('Break Detected');
end;
See Also SioBaud, SioParms, SioRxBuf, SioDone, and SioUART.
PCL4P Reference Manual Page 26
SioRI
Function Reads the Ring Indicator ( RI ) modem status bit.
Syntax function SioRI(Port:Integer) : Integer;
Remarks The SioRI function is used to read the Ring Indicator
( RI ) modem status bit. Also see SioModem.
Returns -2 : Port not enabled. Call SioReset first.
-4 : Port out of range. Expecting 0 to 3.
0 : RI is clear.
>0 : RI is set ( RING has occurred ).
Example
(* read the RI line *)
RetCode := SioRI(Port);
if RetCode > 0 then write('RING');
See Also SioDSR, SioCTS, SioDCD, and SioModem.
PCL4P Reference Manual Page 27
SioRTS
Function Sets, clears, or reads the Request to Send ( RTS )
line.
Syntax function SioRTS(Port:Integer; Cmd:Char) : Integer;
Remarks The SioRTS function controls the Request to Send (
RTS ) bit in the modem control register. Commands (
defined in PCL4P.H ) are:
SetPort ('S') -- set RTS ( ON )
ClrPort ('C') -- clear RTS ( OFF )
ReadPort ('R') -- read RTS
Returns -2 : Port not enabled. Call SioReset first.
-4 : Port out of range. Expecting 0 to 3.
-5 : Command is not one of 'S', 'C', or 'R'.
0 : RTS is OFF (READ Command).
>0 : RTS is ON (READ Command).
Example
(* turn off RTS for modem *)
RetCode := SioRTS(Port,ClrPort);
See Also SioDTR.
PCL4P Reference Manual Page 28
SioRxBuf
Function Sets up receive buffers.
Syntax function SioRxBuf(Port,BufferOfs,BufferSeg,
SizeCode:Integer) : Integer;
Remarks The SioRxBuf function passes the address and size of
the receive buffer to PCL4P. Recall that PCL4P
requires a receive buffer for each port in
simultaneous operation since the receive function is
interrupt driven. SioRxBuf passes the receive buffer
to PCL4P for both the primary ( COM1/COM3 ) and
secondary ( COM2/COM4 ) ports. It must be called
before any incoming characters can be received.
SioRxBuf must be called before SioReset. Buffer size
codes are listed in "PCL4P.H".
Size Code Buffer Size PCL4P.H Name
0 8 bytes Size8
1 16 bytes Size16
2 32 bytes Size32
3 64 bytes Size64
4 128 bytes Size128
5 256 bytes Size256
6 512 bytes Size512
7 1024 bytes Size1024 or Size1K
8 2048 bytes Size2048 or Size2K
9 4096 bytes Size4096 or Size4K
10 8192 bytes Size8192 or Size8K
11 16384 bytes Size16384 or Size16K
12 32768 bytes Size32768 or Size32K
Returns -4 : Port out of range. Expecting 0 to 3.
-10 : Bad buffer size code. Expecting 0 to 11.
Example
(* set up the receive buffer *)
RetCode := SioRxBuf( COM1, Ofs(RxBuf),Seg(RxBuf), 128);
See Also SioReset.
PCL4P Reference Manual Page 29
SioRxFlush
Function To flush the receive buffer associated with the
specified port.
Syntax function SioRxFlush(Port:Integer) : Integer;
Remarks The SioRxFlush function will delete any characters in
the receive buffer for the specified port. After
execution, the receive buffer will be empty. Call
SioRxBuf after resetting a port in order to delete any
spurious characters.
Returns -2 : Port not enabled. Call SioReset first.
-4 : Port out of range. Expecting 0 to 3.
Example
(* setup receive buffer and reset port *)
RetCode := SioRxBuf(COM1,Ofs(Buffer),Seg(Buffer),Size1024);
RetCode := SioReset(COM1,Baud115200);
(* flush any spurious character *)
RetCode := SioRxFlush(COM1);
(* ready for serial processing ! *)
See Also SioRxQue.
PCL4P Reference Manual Page 30
SioRxQue
Function Returns the number of characters in the receive queue.
Syntax function SioRxQue(Port:Integer) : Integer;
Remarks The SioRxQue function will return the number of
characters in the receive queue. It can be used to
implement XON/XOFF flow control.
Returns -2 : Port not enabled. Call SioReset first.
-4 : Port out of range. Expecting 0 to 3.
Example
RetCode := SioRxBuf(COM1,Ofs(Buffer),Seg(Buffer),Size128);
(* implement XON / XOFF *)
count := SioRxQue(COM1);
if (last=XON) and (count>120) then
begin
RetCode := SioPutc(COM1,char(XOFF));
last := XOFF;
end
if (last=XOFF) and (count<8) then
begin
RetCode := SioPutc(COM1,char(XON));
last := XON;
end
See Also SioRxFlush.
PCL4P Reference Manual Page 31
SioTimer
Function Returns the number of system clock tics since
midnight.
Syntax function SioTimer : LongInt;
Remarks The SioTimer function will return the number of system
clock tics since midnight, at 18.2065 tics per second.
This function is usefull for timing various functions.
Also see SioDelay.
Returns timer tics.
Example
Var Time : LongInt;
...
Time := SioTimer();
(* do some stuff *)
Writeln('Elasped time ', SioTimer - Time );
See Also SioDelay.
PCL4P Reference Manual Page 32
SioTxBuf
Function Sets up transmitter buffer.
Syntax function SioTxBuf(Port,BufferOfs,BufferSeg,
SizeCode:Integer) : Integer;
Remarks The SioTxBuf function passes the address and size of
the transmit buffer to PCL4P, provided that you will
link with a PCL4P library with transmitter interrupts
enabled. PCL4P requires a transmit buffer for each
port in simultaneous operation if you are using the
version of the library with transmitter interrupts
enabled (PCL4C_2.LIB). SioTxBuf must be called
before SioReset. Buffer size codes are listed in
"PCL4C.H".
Size Code Buffer Size PCL4C.H Name
0 8 bytes Size8
1 16 bytes Size16
2 32 bytes Size32
3 64 bytes Size64
4 128 bytes Size128
5 256 bytes Size256
6 512 bytes Size512
7 1024 bytes Size1024 or Size1K
8 2048 bytes Size2048 or Size2K
9 4096 bytes Size4096 or Size4K
10 8192 bytes Size8192 or Size8K
11 16384 bytes Size16384 or Size16K
12 32768 bytes Size32768 or Size32K
This function is not used unless the transmitter
interrupts are enabled (PCL4C_2.LIB). Refer to the
PCL4C Users Manual for information on transmitter (TX)
interrupts.
Returns -4 : No such port. Expect 0 to MaxPort.
-10 : Bad buffer size code. Expecting 0 to 11.
Example (* set up the transmit buffer *)
RetCode := SioRxBuf(COM1,Ofs(RxBuf),Seg(RxBuf),128);
See Also SioRxBuf and SioReset.
PCL4P Reference Manual Page 33
SioTxFlush
Function To flush the transmit buffer associated with the
specified port.
Syntax function SioTxFlush(Port : Integer) : Integer;
Remarks The SioTxFlush function will delete any characters in
the transmit buffer for the specified port, provided
that you will link with the PCL4P library with
transmitter interrupts enabled. After execution, the
transmit buffer will be empty.
Once this function is called, any character in the
transmit buffer (put there by SioPutc) will be lost
and therefore not transmitted.
This function is not used unless the transmitter
interrupts are enabled (PCL4C_2.LIB). Refer to the
PCL4C Users Manual for information on transmitter (TX)
interrupts.
Returns -2 : Port not enabled. Call SioReset first.
-4 : No such port. Expect 0 to MaxPort.
Example char buffer[1024];
...
/* setup transmit buffer & reset port */
SioTxBuf(COM1,buffer,Size1024);
SioReset(COM1,Baud115200);
/* flush any spurious character */
SioTxFlush(COM1);
/* ready for serial processing ! */
...
See Also SioTxQue.
PCL4P Reference Manual Page 34
SioTxQue
Function Returns the number of characters in the transmit queue.
Syntax int SioTxQue(Port)
int Port; /* Port selected (COM1 thru COM4) */
Remarks The SioTxQue function will return the number of
characters in the transmit queue at the time of the
call, provided that you will link with a PCL4C library
with transmitter interrupts enabled.
This function is not used unless the transmitter
interrupts are enabled (PCL4C_2.LIB). Refer to the
PCL4C Users Manual for information on transmitter (TX)
interrupts.
Returns -2 : Port not enabled. Call SioReset first.
-4 : No such port. Expect 0 to MaxPort.
Example ...
RetCode := SioTxBuf(COM1,Ofs(Buffer),Seg(Buffer),Size128);
(* display # bytes in TX queue *)
Count := SioTxQue(COM1);
...
See Also SioTxFlush.
PCL4P Reference Manual Page 35
SioTimer
Function Returns the number of system clock tics since
midnight.
Syntax function SioTimer : LongInt;
Remarks The SioTimer function will return the number of system
clock tics since midnight, at 18.2065 tics per second.
This function is usefull for timing various functions.
Also see SioDelay.
Returns timer tics.
Example
Var Time : LongInt;
...
Time := SioTimer();
(* do some stuff *)
Writeln('Elasped time ', SioTimer - Time );
See Also SioDelay.
PCL4P Reference Manual Page 36
SioUART
Function Sets the UART base address.
Syntax function SioUART(Port,Address:Integer) : Integer;
Remarks The SioUART function sets the UART base address for
the specified port. SioUART must be called before
SioReset in order to have effect. Be extremely sure
that you know what you are doing! Note that PCL4P uses
the standard PC/XT/AT port addresses, interrupt
request lines, and interrupt service vectors.
Therefore, this function is only needed for
non-standard ports.
Returns >0 : The previous base address for this port.
-4 : Port out of range. Expecting 0 to 3.
-15 : Port already enabled. SioReset already called.
Example (* Record fact that you don't have COM4 *)
RetCode := SioUART(COM4, 0);
See Also SioReset, SioIRQ.
PCL4P Reference Manual Page 37
SioUnGetc
Function "Un-gets" the last character read with SioGetc().
Syntax function SioUnGetc(Port:Integer; Ch:Char) : Integer;
Remarks The SioUnGetc function returns ( pushes ) the
character back into the serial input buffer. The
character pushed will be the next character returned
by SioGetc. Only one character can be pushed back.
This function works just like the "ungetc" function in
the C language.
Returns -2 : Port not enabled. Call SioReset first.
-4 : Port out of range. Expecting 0 to 3.
Example (* push back c so next SioGetc will get it *)
RetCode := SioUnGetc(Port,c);
See Also SioReset.
PCL4P Reference Manual Page 38
Function Sumary
***********************************************************
* Function * Arg1 * Arg2 * Arg3 * Arg4 *
***********************************************************
* SioBaud * Port * BaudCode * * *
* SioBrkKey * * * * *
* SioBrkSig * Port * Cmd * * *
* SioCTS * Port * * * *
* SioDCD * Port * * * *
* SioDelay * Tics * * * *
* SioDone * Port * * * *
* SioDSR * Port * * * *
* SioDTR * Port * Cmd * * *
* SioError * Code * * * *
* SioFIFO * Port * FIFOcode * * *
* SioFlow * Port * Tics * * *
* SioGetc * Port * Tics * * *
* SioInfo * Cmd * * * *
* SioIRQ * Port * IRQcode * ISRcode * *
* SioLine * Port * * * *
* SioLoopBack * Port * * * *
* SioModem * Port * Mask * * *
* SioParms * Port * Parity * StopBits *WordLength*
* SioPorts * Ports * FirstDB * StatusReg* *
* SioPutc * Port * Ch * * *
* SioRead * Port * Register * * *
* SioReset * Port * BaudCode * * *
* SioRI * Port * * * *
* SioRTS * Port * Cmd * * *
* SioRxBuf * Port * Ofs(Buff)* Seg(Buff)* SizeCode *
* SioRxFlush * Port * * * *
* SioRxQue * Port * * * *
* SioTimer * * * * *
* SioTxBuf * Port * Ofs(Buff)* Seg(Buff)* SizeCode *
* SioTxFlush * Port * * * *
* SioTxQue * Port * * * *
* SioUART * Port * Address * * *
* SioUnGetc * Port * Ch * * *
***********************************************************
( 34 functions)
PCL4P Reference Manual Page 39
Error Code Summary
*****************************************************************
* Code * Description *
*****************************************************************
* 0 * No error. *
* -1 * Timeout waiting for input. (Only returned by SioGetc).*
* -2 * Port not enabled. Call SioReset first. *
* -3 * No buffer available. Call SioRxBuf first. *
* -4 * Port out of range. Expecting 0 to 3. (COM1 = 0) *
* -5 * Expected 'S', 'C', or 'R' as second argument. *
* -6 * Expected 'A', 'C', or 'D' as second argument. *
* -7 * Bad parity code specified. Must be 0 to 7. *
* -8 * Bad stop bits code specified. Must be 0 or 1. *
* -9 * Bad wordlength code specified. Must be 0 to 3. *
* -10 * Bad buffer size code specified. Must be 0 to 11. *
* -11 * Bad baud rate code. Must be 0 to 9. *
* -12 * Loopback test fails. *
* -13 * UART undefined. *
* -14 * Missing or bad UART. *
* -15 * Port already enabled. *
* -16 * Interrupt already in use. *
* -17 * No such IRQ. (Should be 2 to 7) *
* -18 * ISR limit exceeded. *
*****************************************************************
PCL4P Reference Manual Page 40
